Mini Games
Accessing the Mini Game as a Reward
For this section the process will be described using the typescript SDK. If you have any questions please don't hesitate to contact your Customer Success Representative, or reach out for help in one of our support channels.
Once the user has completed the requisites to earn the mini game (completed a mission, won a tournament, leveled up, etc) the game is offered as a reward.
To check its status you can use the the getPlayerRewards method from RewardsProcessor.
const { RewardsProcessor } = GamanzaEngageWebClientSDK.getInstance();
const response = await RewardsProcessor.getPlayerRewards({
limit: 25,
page: 2,
playerId: payload.playerId,
rewardType: RewardTypeEnum.MINI_GAME,
status: [
RewardStatusEnum.IN_PROGRESS,
RewardStatusEnum.PENDING,
RewardStatusEnum.BOUNCED,
],
});
This will return a paginated list of the rewards of type “mini_game” that looks like this
{
"docs": [
{
"_id": "68e6c87e1b9f805ed842fe9d",
"status": "in_progress",
"playerId": "Ryder_Kuvalis",
"date": "2025-10-08T20:24:30.686Z",
"source": "missions",
"activation": "automatic",
"group": {
"groupId": "c1e8809d-3454-41e9-baed-4830e894c3fb",
"totalItems": 1
},
"earnedReward": {
"type": "mini_game",
"expirationValidityTime": {
"timeType": "any_time"
},
"termsAndConditions": [],
"miniGameOfferId": "68e56c07797e15c526c1adc2",
"miniGameOfferName": "INTERNAL NAME",
"translations": [
{
"description": "EXTERNAL DE",
"language": "DE"
},
{
"description": "EXTERNAL EN",
"language": "EN"
},
{
"description": "EXTERNAL FR",
"language": "FR"
}
],
"brandId": "default",
"uniqueIdentifier": "3d34d199-5786-4b53-9359-cac4f3c4ab6d"
},
"metadata": {
"missionId": "68e56c773eb477da71682570",
"bundleId": "68e56cb83eb477da71682660",
"missionDescription": "Mini Game Test",
"missionBundleExternalDetails": [],
"rewardId": "68e56c773eb477da71682575",
"bundleStateId": "68e6c804799a173bff889ec3",
"missionStateId": "68e6c804799a173bff889ec5"
},
"trigger": "on-missions-complete",
"createdAt": "2025-10-08T20:24:30.690Z",
"updatedAt": "2025-10-08T20:24:30.701Z",
"__v": 0,
"id": "68e6c87e1b9f805ed842fe9d"
},
{...},
{...}
],
"totalDocs": 3,
"limit": 100,
"totalPages": 1,
"page": 1,
"pagingCounter": 1,
"hasPrevPage": false,
"hasNextPage": false,
"prevPage": null,
"nextPage": null
}
The metadata key will vary depending on the reward source. In this example, the reward was awarded through a mission, hence the mission-related metadata.
Claiming the Mini Game
There is a Feature Flag inside Settings called “Are rewards activated by players?” that determines the first status of the given rewards.
-
If the flag is Enabled: the rewards will have status “unclaimed”, and they need to be claimed in order to be awarded to the player.
-
If the flag is Disabled: the rewards will be claimed automatically upon being earned.
To claim a mini game, you can call the playerClaimRewardsByGroupId method (you can find the groupId inside the Reward object under group.groupId)
const { RewardsProcessor } = GamanzaEngageWebClientSDK.getInstance();
const response = await RewardsProcessor.playerClaimRewardsByGroupId(groupId);
Delivering the Game
To deliver the game you’ll need to generate a unique URL. To do this, the game should be in a playable state (in_progress, bounced), otherwise you’ll receive an error response.
Use the generatePlayerMiniGameRewardLaunchUrl method from the SDK for this,
all the parameters are available inside the rewards response you got earlier.
const { MiniGames } = GamanzaEngageWebClientSDK.getInstance();
const myGame = docs[0].earnedReward;
const result = await MiniGames.generatePlayerMiniGameRewardLaunchUrl(
myGame.miniGameOfferId,
uniqueIdentifier
);
if (result.ok) {
const url = result.data.url;
}
The received url is composed by a main URL and a token param.
Do not modify the token as it is needed by the game to load properly.
- That url can be used in any browser or iframe to access the game offer and play the game!
-
The token has a 1 hour expiration, so it is not ideal to generate the url in advance, it should be generated at the time the player wants to play.
-
The url contains some encoded data that the game needs to launch, including the API url that it needs to call to load its settings and to send the results, make sure you have the correct url set up in your admin settings under Core Features → Frontend API:
Claiming Game Rewards
After successfully completing a game the player will be presented with the option to Claim or Decline their rewards. Once claimed they will move to the player’s inventory.
If Declined, the rewards won’t be accessible by the player, but admins can see the declined status in the Player Card.
If the player closes the game before claiming their rewards or loses connection, the rewards will remain unclaimed in the database and can be claimed manually by an admin via the player card or the API using the rewards groupId as a parameter (the same way you claim the Mini Game when awarded)
const { RewardsProcessor } = GamanzaEngageWebClientSDK.getInstance();
const response = await RewardsProcessor.playerClaimRewardsByGroupId(groupId);
Closing the game
Once the Rewards are Claimed or Declined, the game will present the player with a “Close Game” button, this button behaves differently depending on how the game was launched:
- If the game was launched inside an iFrame, it will signal its parent with a "GAME_OVER" message, that can be used to close or destroy the iFrame, here is an example of a React application listening to the message:
useEffect(() => {
const handleMessage = (event: MessageEvent) => {
if (event.data?.type === "GAME_OVER") {
// Logic to destroy the iFrame goes here
}
};
window.addEventListener("message", handleMessage);
return () => window.removeEventListener("message", handleMessage);
}, []);
-
If the game is in a standalone browser window it will call window.close() that will close the window or tab if
- It was opened using window.open()
- It was opened via web content